home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 October: Mac OS SDK / Dev.CD Oct 00 SDK1.toast / Development Kits / Mac OS / GameSprocket SDKs / SoundSprocket_SDK / SoundSprocket Release Notes < prev    next >
Encoding:
Text File  |  1999-10-29  |  6.9 KB  |  161 lines  |  [ttro/ttxt]
  1. SoundSprocket 1.7
  2. Release Notes
  3. -----------------
  4.  
  5. Please report all bugs using the bug reporter on Apple Developer Connection:
  6.  
  7. <http://developer.apple.com/bugreporter/index.html>
  8.  
  9. Release Components
  10. ------------------
  11.  
  12. SoundSprocket Release Notes                - this file
  13. SoundSprocket.h                            - the header file to compile with
  14. SoundSprocketLib                        - release version of the library
  15. SoundSprocketDebugLib                    - debugging version of the library
  16. SoundSprocket Filter                    - the filter component
  17. SoundSprocket Debug Filter                - debugging version of the filter
  18.  
  19. WARNING: don't place both the debugging and non-debugging versions of the
  20. library in the search path or you will not be sure which version you will be
  21. using.
  22.  
  23. Either SoundSprocket Filter or SoundSprocket Debug Filter must be present in
  24. the Extensions folder at boot- and run-time.  Only one of them should be
  25. present or you will not be sure which version you are using.
  26.  
  27. Dependencies
  28. ------------
  29.  
  30. SoundSprocket requires Mac OS 8.1 or later to load and operate.
  31.  
  32.  
  33.  
  34. Changes from version 1.0:
  35. -----------------------
  36. The rendering engine has been completely replaced with the enCompass positional 
  37. audio technology from Spatializer Audio Laboratories, Inc.  This new renderer 
  38. should be backward compatible with existing apps using SoundSprocket v1.0, 
  39. however, there are some changes that developers should be aware of:
  40.  
  41. The new renderer supports two resolutions:  hi-res is CPU load 0, and low-res 
  42. is CPU load 1.  The hi-res mode consumes approximately 4.8% of a 300 MHz CPU per 
  43. source; low-res is 2.6% per source.  The reverb adds an additional 5.0% per source.  
  44. The renderer is currently running at 44.1 kHz, so sample rate convert your sounds 
  45. to 44.1 to avoid rate conversion by the Sound Manager.
  46.  
  47. The SSpConfigureSetup high-level library call should no longer be used.  Use the 
  48. low-level interface to get and set the speaker (audio display) configuration.  In 
  49. addition, use kSSpSpeakerKind_Stereo for 2-channel speakers and 
  50. kSSpSpeakerKind_Headphones for headphones.  Mono output is not supported.
  51.  
  52. The roomSize parameter for the reverb now specifies one of three different room 
  53. sizes.   A size of 0 to 10 meters uses the small room model, 10 to 20 meters uses 
  54. the medium room, and 20 to 40 meters for the large reverb.  Alternatively use 1, 
  55. 11, and 21 for the small, medium, and large rooms respectively.
  56.  
  57. The automatic switching to and from ambient mode in certain conditions has been
  58. removed from the high-level lib and filter.  Ambient mode will only be active if 
  59. it has been turned on by a call to SSpSource_SetMode or the sourceMode
  60. field in the SSpLocalizationData struct is modified directly.
  61.  
  62. There are now OpenGL calling-convention versions of all of the API calls which 
  63. take vectors, points or matrices.  Function names ending in 'fv' take an array of 
  64. floats as an argument.  These floats are in x, y, z order.  The functions that 
  65. deal with transforms take a 4x4 matrix of floats.  These matrices are made up of 
  66. 16 floats in column-major order (same as OpenGL but the opposite of C).
  67.  
  68.  
  69. Special Considerations
  70. ----------------------
  71.  
  72.     -    If you play a sound using SndPlay, SndStartFilePlay or by sending a
  73.         bufferCmd, when the sound ends, the reverb will stop abruptly.  Worse,
  74.         this reverb tail is stored in internal buffers, and will continue when
  75.         the next sound is played in the sound channel if care is not taken.
  76.         
  77.         To fix the reverb from stopping abruptly for sounds played with these
  78.         methods, pad the sounds with enough silence to ensure that the reverb
  79.         has quieted down.
  80.         
  81.         To fix the reverb tail from showing up in the next sound, the buffers
  82.         can be flushed by sending a quietCmd to the buffer.  In general it is
  83.         a good idea to send a quietCmd between sounds separated by a gap in
  84.         time.
  85.     
  86.     -    To stop a sound while it is playing, but continue the reverb, you need
  87.         to pause the sound, wait for enough time for the reverb to run out, and
  88.         stop the sound.  If you are playing the sound with a bufferCmd then
  89.         this is a sequence of commands, rateCmd(0), wait(interval) and
  90.         quietCmd.  If you are playing the sound from disk then this is
  91.         a SndPauseFilePlay followed after the interval by a SndStopFilePlay.
  92.  
  93. API/Documentation Conflicts
  94. ---------------------------
  95.     
  96.     -    The SoundSprocket Filter contains resources that define a pane of the
  97.         Sound control panel.  The pane allows the user to control the speaker
  98.         kind and angle, much like SSpConfigureSpeakerSetup.  You may choose to
  99.         install the Sound control panel with your game, or provide a menu or
  100.         button to access SSpConfigureSpeakerSetup, or both.
  101.     
  102.     -    After the documentation was completed, it was decided that the SSpSetup
  103.         names were not specific enough.  We renamed them to SSpSpeakerSetup.
  104.         Some #defines are included in SoundSprocket.h to allow code to be
  105.         written per the documentation.  But please use the new, longer names,
  106.         as the #defines will be removed in a later release.
  107.         
  108.                 OLD NAME                NEW NAME
  109.                 siSSpSetup                siSSpSpeakerSetup
  110.                 SSpSetupData            SSpSpeakerSetupData
  111.                 SSpConfigureSetup        SSpConfigureSpeakerSetup
  112.  
  113.     -    The SndGetInfo selector siSSpFilterVersion and datatype
  114.         SSpFilterVersionData have been removed in favor of an alternate way of
  115.         accessing filter version information.  The following function may be
  116.         used for this purpose.
  117.  
  118. // **************************** GetSSpFilterVersion ****************************
  119. // Finds the manufacturer and version number of the SoundSprocket filter that
  120. // may be installed.  inManufacturer should be the manufacturer code specified
  121. // at the installation time, which may be zero to allow any manufacturer.
  122. // If no error is encountered, outManufacturer is set to the actual manufacturer
  123. // code and outMajorVersion and outMinorVersion are set to the component
  124. // specification level and manufacturer's implementation revision, respectively.
  125. OSStatus GetSSpFilterVersion(
  126.     OSType                    inManufacturer,
  127.     OSType*                    outManufacturer,
  128.     UInt32*                    outMajorVersion,
  129.     UInt32*                    outMinorVersion)
  130. {
  131.     OSStatus                err;
  132.     ComponentDescription    description;
  133.     Component                componentRef;
  134.     UInt32                    vers;
  135.     
  136.     // Set up the component description
  137.     description.componentType            = kSoundEffectsType;
  138.     description.componentSubType        = kSSpLocalizationSubType;
  139.     description.componentManufacturer    = inManufacturer;
  140.     description.componentFlags            = 0;        
  141.     description.componentFlagsMask        = 0;    
  142.     
  143.     // Find a component matching the description
  144.     componentRef = FindNextComponent(nil, &description);
  145.     if (componentRef == nil)  return couldntGetRequiredComponent;
  146.     
  147.     // Get the component description (for the manufacturer code)
  148.     err = GetComponentInfo(componentRef, &description, nil, nil, nil);
  149.     if (err != noErr)  return err;
  150.     
  151.     // Get the version composite
  152.     vers = (UInt32) GetComponentVersion((ComponentInstance) componentRef);
  153.     
  154.     // Return the results
  155.     *outManufacturer = description.componentManufacturer;
  156.     *outMajorVersion = HiWord(vers);
  157.     *outMinorVersion = LoWord(vers);
  158.     
  159.     return noErr;
  160. }
  161.